import time
from functools import wraps


def timer(format_str="函数 {func_name} 运行时间: {time:.6f} 秒"):
    """
    计算函数运行时间的装饰器

    参数:
        format_str: 自定义输出格式，支持的占位符有：
            {func_name}: 函数名称
            {time}: 运行时间（秒）
            {args}: 函数 positional 参数
            {kwargs}: 函数 keyword 参数
    """

    def decorator(func):
        @wraps(func)  # 保留原函数的元信息（如名称、文档字符串）
        def wrapper(*args, **kwargs):
            # 记录开始时间
            start_time = time.perf_counter()  # 高精度计时，适合短时间测量

            # 执行被装饰的函数
            result = func(*args, **kwargs)

            # 计算运行时间
            end_time = time.perf_counter()
            run_time = end_time - start_time

            # 格式化输出
            print(format_str.format(
                func_name=func.__name__,
                time=run_time,
                args=args,
                kwargs=kwargs
            ))

            # 返回原函数的执行结果
            return result

        return wrapper

    return decorator